home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / bit / Bit.man < prev    next >
Text File  |  1988-12-31  |  4KB  |  108 lines
  1. ' $Header: /sprite/src/lib/c/bit/RCS/Bit.man,v 1.1 88/12/30 13:26:50 ouster Exp $ SPRITE (Berkeley)
  2. .so \*(]ltmac.sprite
  3. .HS Bit lib
  4. .BS
  5. .SH NAME
  6. Bit_Set, Bit_Clear, Bit_IsSet, Bit_IsClear, Bit_Copy, 
  7. Bit_Zero, Bit_FindFirstSet, Bit_FindFirstClear,
  8. Bit_Intersect, Bit_Union, Bit_AnySet, Bit_Expand,
  9. Bit_Alloc, Bit_Free \- bit operations
  10. .SH SYNOPSIS
  11. .nf
  12. #include <bit.h>
  13. .sp
  14. \fBBit_Set\fR(\fIbitNum, arrayPtr\fP)
  15.  
  16. \fBBit_Clear\fR(\fIbitNum, arrayPtr\fP)
  17.  
  18. \fBBit_IsSet\fR(\fIbitNum, arrayPtr\fP)
  19.  
  20. \fBBit_IsClear\fR(\fIbitNum, arrayPtr\fP)
  21.  
  22. \fBBit_Copy\fR(\fInumBits, srcArrayPtr, destArrayPtr\fP)
  23.  
  24. \fBBit_Zero\fR(\fInumBits, arrayPtr\fP)
  25.  
  26. \fBBit_FindFirstSet\fR(\fInumBits, arrayPtr\fP)
  27.  
  28. \fBBit_FindFirstClear\fR(\fInumBits, arrayPtr\fP)
  29.  
  30. Boolean
  31. \fBBit_Intersect\fR(\fInumBits, array1Ptr, array2Ptr, destArrayPtr\fP)
  32.  
  33. Boolean
  34. \fBBit_Union\fR(\fInumBits, array1Ptr, array2Ptr, destArrayPtr\fP)
  35.  
  36. Boolean
  37. \fBBit_AnySet\fR(\fInumBits, arrayPtr\fP)
  38.  
  39. int *
  40. \fBBit_Expand\fR(\fInewNumBits, oldNumBits, oldArrayPtr\fP)
  41.  
  42. \fBBit_Alloc\fR(\fInumBits, arrayPtr\fP)
  43.  
  44. \fBBit_Free\fR(\fIarrayPtr\fP)
  45. .SH ARGUMENTS
  46. .AP int bitNum in
  47. The number in the array of the bit to manipulate.
  48. .AP int numBits in
  49. The number of bits in all the \fI*arrayPtr\fP variables passed.
  50. .AP int *arrayPtr in,out
  51. The array of bits.
  52. .AP int *srcArrayPtr in
  53. The array of bits to be copied.
  54. .AP int *destArrayPtr out
  55. The array to which bits are copied.
  56. .AP int *array1Ptr in
  57. The first source array in an intersection or union operation.
  58. .AP int *array2Ptr in
  59. The second source array in an intersection or union operation.
  60. .AP int newNumBits in
  61. The number of bits the expanded array must hold.
  62. .AP int oldNumBits in
  63. The number of bits in the old array.
  64. .AP int *oldArrayPtr in
  65. The bit array that is now too small.
  66. .BE
  67. .SH DESCRIPTION
  68. These procedures manipulate integer arrays of bits.  All the procedures
  69. operate on integer arrays and \fInumBits\fP is used to compute the size
  70. of \fI*arrayPtr\fP. If \fInumBits\fP is not a multiple of the number of
  71. bits in an integer, it is rounded up to the nearest multiple.
  72. .PP
  73. \fBBit_Set\fR sets the \fIbitNum\fP bit in \fI*arrayPtr\fP.
  74. .br
  75. \fBBit_Clear\fR clears the \fIbitNum\fP bit in \fI*arrayPtr\fP.
  76. .PP
  77. The predicates \fBBit_IsSet\fR and \fBBit_IsClear\fR test to see if 
  78. the \fIbitNum\fP bit is set or cleared.
  79. .PP
  80. \fBBit_Zero\fR clears all bits in \fI*arrayPtr\fR.
  81. .br
  82. \fBBit_Copy\fR copies \fI*srcArrayPtr\fR to \fI*destArrayptr\fR.
  83. .PP
  84. \fBBit_FindFirstSet\fR and \fBBit_FindFirstClear\fR return the index of the
  85. rightmost bit in \fI*arrayPtr\fP that is set or cleared. The index
  86. begins at 0 and -1 is returned if no set or cleared bit is found.
  87. .PP
  88. \fBBit_Intersect\fR and \fBBit_Union\fR find the intersection and union, respectively,
  89. of the two bit arrays and stores the result in the third array. They
  90. return TRUE if the intersection or union is non-empty. For both functions,
  91. if \fIdestArrayPtr\fP is NULL, the result is not stored anywhere.
  92. .PP
  93. \fBBit_AnySet\fR examines the array to see if any of the bits is on, returning
  94. TRUE if at least one is set and FALSE otherwise.
  95. .PP
  96. \fBBit_Alloc\fR and \fBBit_Free\fR are used to allocate and free bit arrays.
  97. \fBBit_Alloc\fR creates an array to hold \fInumBits\fP bits and sets \fIarrayPtr\fP
  98. to point at it. The array initially has no bits set. \fBBit_Free\fR deallocates
  99. a previously-allocated bit array.
  100. .PP
  101. \fBBit_Expand\fR takes an existing, dynamically-allocated array, \fIoldArrayPtr\fP,
  102. along with its width, \fIoldNumBits\fP, and expands it to contain
  103. \fInewNumBits\fP bits, returning a pointer to the expanded array. The array may
  104. or may not have moved. If the array was moved, the old array was deallocated
  105. at the same time. The new bits are initially all 0.
  106. .SH KEYWORDS
  107. bit, set, clear, copy, zero
  108.